Ad-hoc 与模块速查
本篇收录 ad-hoc（一次性命令）的完整格式和日常使用频率最高的模块参数，按场景分组，随用随查。模块名统一使用 FQCN 全名，适用于 ansible-core 2.16/2.17。
命令格式
ansible <主机模式> -m <模块> -a "模块参数" [-b] [-i <inventory>]
<主机模式>：all、组名、主机名，或web*:&prod这类组合表达式-m：指定模块，省略时默认ansible.builtin.command-a：模块参数，整体用引号包住，格式为key=value空格分隔-b：提权执行（become，默认 sudo 到 root），需要密码时再加-K-i：指定 inventory 文件，省略时使用 ansible.cfg 里的inventory配置
一个完整的例子，检查 web 组所有主机的 nginx 服务是否运行：
ansible web -i inventory.ini -b -m ansible.builtin.service -a "name=nginx state=started"
连通与调试
| 模块 | 用途 | 常用参数 | 示例 |
|---|---|---|---|
ansible.builtin.ping | 验证 SSH 连通性和被控端 Python 可用 | 无 | ansible web -m ansible.builtin.ping |
ansible.builtin.command | 直接执行命令，不经过 shell | creates、chdir | ansible web -m ansible.builtin.command -a "uptime" |
ansible.builtin.shell | 经 /bin/sh 执行，支持管道重定向 | 同 command | ansible web -m ansible.builtin.shell -a "df -h | grep /$" |
ansible.builtin.debug | 打印变量或消息，调试 playbook 用 | msg、var | ansible web -m ansible.builtin.debug -a "var=ansible_facts['os_family']" |
command 与 shell 的选择
能不用 shell 特性就用 command：不经过 shell 解释，没有注入风险，配合 creates 参数还能做到基本的幂等。只有确实需要管道、重定向、通配符时才换 shell。
包管理
| 模块 | 用途 | 常用参数 | 示例 |
|---|---|---|---|
ansible.builtin.package | 跨发行版抽象包管理，自动选择后端 | name、state | ansible web -b -m ansible.builtin.package -a "name=nginx state=present" |
ansible.builtin.apt | Debian/Ubuntu 系包管理 | name、state、update_cache | ansible web -b -m ansible.builtin.apt -a "name=nginx state=present update_cache=true" |
ansible.builtin.dnf | RHEL/Fedora/Rocky 系包管理 | name、state | ansible web -b -m ansible.builtin.dnf -a "name=nginx state=latest" |
ansible.builtin.yum | 旧版 RHEL/CentOS 包管理 | name、state | ansible web -b -m ansible.builtin.yum -a "name=vim state=present" |
ansible.builtin.pip | Python 包管理 | name、state、virtualenv | ansible web -m ansible.builtin.pip -a "name=requests state=present" |
服务管理
| 模块 | 用途 | 常用参数 | 示例 |
|---|---|---|---|
ansible.builtin.service | 通用服务管理，兼容各 init 系统 | name、state、enabled | ansible web -b -m ansible.builtin.service -a "name=nginx state=started enabled=true" |
ansible.builtin.systemd | systemd 单元管理，支持 reload 单元文件 | name、state、enabled、daemon_reload | ansible web -b -m ansible.builtin.systemd -a "name=nginx state=restarted daemon_reload=true" |
state 的取值
started / stopped / restarted / reloaded 四种。改配置文件后要生效用 reloaded（服务支持 reload 时）或 restarted；日常巡检确认在跑用 started，已运行的不会重复启动。
文件与内容
| 模块 | 用途 | 常用参数 | 示例 |
|---|---|---|---|
ansible.builtin.copy | 推送本地文件或内联内容到被控端 | src、dest、content、mode、backup | ansible web -b -m ansible.builtin.copy -a "src=./app.conf dest=/etc/app.conf mode=0644 backup=true" |
ansible.builtin.template | 渲染 Jinja2 模板后推送 | src、dest、mode | ansible web -b -m ansible.builtin.template -a "src=nginx.conf.j2 dest=/etc/nginx/nginx.conf" |
ansible.builtin.file | 管理文件/目录/链接的属性 | path、state、mode、owner | ansible web -b -m ansible.builtin.file -a "path=/data state=directory mode=0755" |
ansible.builtin.lineinfile | 确保某行存在或按正则改写 | path、regexp、line | ansible web -b -m ansible.builtin.lineinfile -a "path=/etc/hosts line='192.168.1.10 db.local'" |
ansible.builtin.blockinfile | 管理带标记的整段文本块 | path、block、marker | ansible web -b -m ansible.builtin.blockinfile -a "path=/etc/profile block='export EDITOR=vim'" |
ansible.builtin.fetch | 从被控端拉文件回控制端 | src、dest、flat | ansible web -m ansible.builtin.fetch -a "src=/var/log/messages dest=./logs/ flat=true" |
用户与权限
| 模块 | 用途 | 常用参数 | 示例 |
|---|---|---|---|
ansible.builtin.user | 管理用户账号 | name、state、groups、shell | ansible all -b -m ansible.builtin.user -a "name=deploy shell=/bin/bash groups=wheel" |
ansible.builtin.group | 管理用户组 | name、state | ansible all -b -m ansible.builtin.group -a "name=ops state=present" |
ansible.builtin.authorized_key | 分发 SSH 登录公钥 | user、key | ansible all -b -m ansible.builtin.authorized_key -a "user=deploy key=\"{{ lookup('file', '~/.ssh/id_ed25519.pub') }}\"" |
网络与下载
| 模块 | 用途 | 常用参数 | 示例 |
|---|---|---|---|
ansible.builtin.get_url | 下载文件到被控端 | url、dest、mode、checksum | ansible web -b -m ansible.builtin.get_url -a "url=https://example.com/app.tar.gz dest=/tmp/app.tar.gz" |
ansible.builtin.uri | 发起 HTTP 请求，探测接口 | url、method、status_code | ansible web -m ansible.builtin.uri -a "url=http://localhost:8080/health status_code=200" |
ansible.builtin.wait_for | 等待端口开放或文件出现 | port、host、timeout | ansible web -m ansible.builtin.wait_for -a "port=5432 host=db timeout=30" |
定时任务
| 模块 | 用途 | 常用参数 | 示例 |
|---|---|---|---|
ansible.builtin.cron | 管理 crontab 条目 | name、job、minute、hour、weekday、user | ansible all -b -m ansible.builtin.cron -a "name=daily-backup job='/opt/backup.sh' hour=2 minute=0" |
系统信息
| 模块 | 用途 | 常用参数 | 示例 |
|---|---|---|---|
ansible.builtin.setup | 采集主机 facts（系统、硬件、网络） | filter（按模式过滤 fact 名） | ansible web -m ansible.builtin.setup -a "filter=ansible_distribution*" |
ansible.builtin.service_facts | 采集所有服务的状态 facts | 无 | ansible web -b -m ansible.builtin.service_facts |
ansible.builtin.package_facts | 采集已安装软件包的 facts | manager | ansible web -b -m ansible.builtin.package_facts -a "manager=auto" |
setup 采集量大时的用法
facts 默认采集全部内容，输出很长。临时查看用 filter= 只取关心的前缀，例如 filter=ansible_memtotal_mb、filter=ansible_default_ipv4。
command / shell / raw 怎么选
| 模块 | 执行方式 | 能力 | 适用场景 |
|---|---|---|---|
ansible.builtin.command | 直接执行，不经过 shell | 不支持管道、重定向、通配符；可用 creates/removes 判断跳过 | 执行简单命令的默认首选（-m 省略时的默认模块） |
ansible.builtin.shell | 经被控端 /bin/sh 执行 | 支持管道、重定向、通配符、变量展开 | 必须用 shell 特性时；拼接不可信输入有注入风险 |
ansible.builtin.raw | 直接经 SSH 下发原始命令，不依赖被控端 Python | 几乎没有模块能力，不做幂等和参数检查 | 被控端未装 Python（先装 Python）、网络设备等极端场景 |